<h1>Using Drush to Upgrade Drupal 6.x to Drupal 7.x</h1>
<p>
The drush site-upgrade command supports upgrades from Drupal 6.x
to Drupal 7.x.  Upgrades from Drupal 7.x to Drupal 8.x will be
supported in the future.  Use the drush pm-update command to do minor verison
updates for Drupal 5.x, 6.x and 7.x.
<p>
To begin, consult the UPGRADE.txt file from the root folder of the
version of Drupal you are upgrading to.  Drush will handle some of
the steps described there, but not all.  In particular, you should
make sure that your current Drupal installation is running on the
most recent minor version available.
<p>
n.b. At the time of this writing, Drupal 6.20 and Drupal 7.0 were
the most recent versions available.  Always check primary sources
prior to upgrading to see if anything may have changed.

<h2>Upgrade a Copy of your Site</h2>
<p>
Drush will always upgrade <i>from</i> the specified Drupal site
<i>to</i> an empty Drupal site.  It is necessary to create a
site alias to describe the destination site.  Site aliases are
described in `drush topic docs-aliases`.  A canonical site alias
is adequate to define your target site for upgrade:
<p>
$aliases['onward'] = { <br>
  'root' => '/path/to/upgraded/drupalroot',<br>
  'uri' => 'http://onward.mysite.org',<br>
}<br>
<p>
Optionally, you might also want to define 'db_url' to specify
the name of your target database.  If you do not, drush will
compose a database name for you based on the name of your site alias.
<p>
<h2>Running the `site-upgrade` Command</h2>
<p>
Drush will upgrade the current bootstrapped site, and will
put the result in the target site specified by the argument
to the command.  For example:
<p>
drush @from site-upgrade @onward
<p>
The site-upgrade command will perform the following operations:
<ol>
<li>Download the next major release of Drupal and store the files
in the target site.</li>
<li>Write a new settings.php file with an appropriate databases
structure for the new target site.</li>
<li>Make a copy of the SQL database for the new site.</li>
<li>The default theme for the new site will be set to "garland",
and the admin theme will be set to "seven".</li>
<li>All non-core extensions will be disabled in the target database,
and updatedb will be run on Drupal core.</li>
<li>All of the modules disabled in the previous step will be
downloaded again, if they have an appropriate version for the
target Drupal site available.</li>
<li>updatedb will be run again to update the non-core modules.</li>
<li>All of the non-core modules will be enabled again.</li>
</ol>
<p>
Before drush begins this process, it will first print out a list
of warnings for any modules that may not be ready to upgrade yet.
Please read all of these messages carefully before proceding.
Here are some of the situations you may encounter.
<ul>
<li>If a module has no <i>recommended</i> release, then drush
will continue, downloading an available release for the upgrade.</li>
<li>If a module has no release at all, then drush will skip it.
The module's data will remain in the database.</li>
<li>You may discover that some modules, such as date_api, might
cause the Drupal core updatedb to fail.  In this instance, you
may use the --uninstall option to list the modules to uninstall
prior to upgrade.  Modules uninstalled in this manner will have
all of their data removed from the target database; the database
of the source site is not affected.</li>
</ul>
<p>
When drush is enabling the modules in the upgraded site, if there
are any new dependencies, they will also be identified and downloaded
if possible.  For example, views-7.x depends on the ctools module
from the Chaos tool suite, whereas views-6 did not; drush will therefore
download and enable ctools when upgrading the views module from
Drupal 6 to Drupal 7.
<p>
There will still be some work left to do after the site-upgrade
command has completed; for example, you will still need to port your
theme and any custom modules to the new version of Drupal, and some
contrib modules may require additional work to update their configuration
settings.  Using site-upgrade will all the same save you a considerable
amount of time.  There is no risk in trying it; if it does not work,
you can always start over, or run it at a later date when more contrib
modules have been updated.  If you do run site-upgrade a second time
on the same site, drush will ask you if you want to replace the existing
target site, effectively starting over from the beginning, or re-use
the site that is already present.  In the later case, drush will use
the existing code, but will re-copy the source database and run updatedb
on it again.  This will all you to attempt to fix any non-working contrib
modules yourself to get your site-upgrade working.
<p>
Enjoy!
